<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"/>
<title>DynamoRIO API: Usage Model for DynamoRIO</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">DynamoRIO API
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('using.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Usage Model for DynamoRIO </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p>This section gives an overview of how to use DynamoRIO, divided into the following sub-sections:</p>
<ul>
<li><a class="el" href="using.html#sec_events">Common Events</a></li>
<li><a class="el" href="using.html#sec_utils">Common Utilities</a></li>
<li><a class="el" href="using.html#sec_build">Building a Client</a></li>
<li><a class="el" href="using.html#sec_extlibs">Using External Libraries</a></li>
<li><a class="el" href="using.html#sec_extensions">DynamoRIO Extensions</a></li>
<li><a class="el" href="using.html#sec_comm">Communication</a></li>
<li><a class="el" href="using.html#sec_64bit_reach">64-Bit Reachability</a></li>
<li><a class="el" href="using.html#sec_utf8">String Encoding</a></li>
<li><a class="el" href="using.html#sec_options">Fine-Tuning DynamoRIO: Runtime Parameters</a></li>
<li><a class="el" href="using.html#sec_debugging">Diagnosing and Reporting Problems</a></li>
</ul>
<p>DynamoRIO exports a rich Application Programming Interface (API) to the user for building a DynamoRIO <em>client</em>. A DynamoRIO client is a library that is coupled with DynamoRIO in order to jointly operate on an input program binary:</p>
<div class="image">
<img src="client.png" alt="client.png"/>
</div>
  <p>To interact with the client, DynamoRIO provides specific events that a client can intercept. Event interception functions, if supplied by a user client, are called by DynamoRIO at appropriate times.</p>
<p>DynamoRIO can alternatively be used as a third-party disassembly library (see <a class="el" href="page_standalone.html">IA-32/AMD64 Disassembly Library</a>).</p>
<h1><a class="anchor" id="sec_events"></a>
Common Events</h1>
<p>A client's primary interaction with the DynamoRIO system is via a set of event callbacks. These events include the following:</p>
<ul>
<li>Basic block and trace creation or deletion (<a class="el" href="dr__events_8h.html#a043a3588c4cf0c2d6838140fce530e72">dr_register_bb_event()</a>, <a class="el" href="dr__events_8h.html#a88a19a6822654caf18c017e145f48a57">dr_register_trace_event()</a>, <a class="el" href="dr__events_8h.html#a698501b03d64f07e1a32fc82c021b27a">dr_register_delete_event()</a>)</li>
<li>Process initialization and exit (<a class="el" href="dr__api_8h.html#a20a4dc9da7f6bb9121e30bb3570c6961">dr_init()</a>, <a class="el" href="dr__events_8h.html#a985537df683007e1392e8a3b095ef363">dr_register_exit_event()</a>)</li>
<li>Thread initialization and exit (<a class="el" href="dr__events_8h.html#a878920c40c76e2c18043f9db772a24c0">dr_register_thread_init_event()</a>, <a class="el" href="dr__events_8h.html#a0b0c102bb9a99d67c3e62ea8b3790ff1">dr_register_thread_exit_event()</a>)</li>
<li>Fork child initialization (Linux-only); meant to be used for re-initialization of data structures and creation of new log files (<a class="el" href="dr__events_8h.html#a82afd28406cbf06396e1a17ab100c6ea">dr_register_fork_init_event()</a>)</li>
<li>Application library load and unload (<a class="el" href="dr__events_8h.html#aca6b098123ef80cae05ce767a7dd9d98">dr_register_module_load_event()</a>, <a class="el" href="dr__events_8h.html#a2a40613f5e73d800acaeadd400bb1fab">dr_register_module_unload_event()</a>)</li>
<li>Application fault or exception (signal on Linux) (<a class="el" href="dr__events_8h.html#a69adae9409a1871149da69e97747b84c">dr_register_exception_event()</a>, <a class="el" href="dr__events_8h.html#a3ac512c0bd9feea08cb04dd923efb589">dr_register_signal_event()</a>)</li>
<li>System call interception: pre-system call, post-system call, and system call filtering by number (<a class="el" href="dr__events_8h.html#aa37d61a7f9dde4663b8dd4c3a44732f4">dr_register_pre_syscall_event()</a>, <a class="el" href="dr__events_8h.html#a099441f8d147404355c66178e3b19f0f">dr_register_post_syscall_event()</a>, <a class="el" href="dr__events_8h.html#a7ec572232450344efcba8923cae71d51">dr_register_filter_syscall_event()</a>)</li>
<li>Signal interception (Linux-only) (<a class="el" href="dr__events_8h.html#a3ac512c0bd9feea08cb04dd923efb589">dr_register_signal_event()</a>)</li>
<li>Nudge received - see <a class="el" href="using.html#sec_comm">Communication</a> (<a class="el" href="dr__events_8h.html#a9037603d0bd5bfca4198011adb8d10eb">dr_register_nudge_event()</a>)</li>
</ul>
<p>Typically, a client will register for the desired events at initialization in its <a class="el" href="dr__api_8h.html#a20a4dc9da7f6bb9121e30bb3570c6961">dr_init()</a> routine. DynamoRIO then calls the registered functions at the appropriate times. Each event has a specific registration routine (e.g., <a class="el" href="dr__events_8h.html#a878920c40c76e2c18043f9db772a24c0">dr_register_thread_init_event()</a>: see the names in parentheses in the list above) and an associated unregistration routine. The header file <a class="el" href="dr__events_8h.html" title="Event callback registration routines.">dr_events.h</a> contains the declarations for all registration and unregistration routines.</p>
<p>Note that clients are allowed to register multiple callbacks for the same event. DynamoRIO also supports mutiple clients, each of which can register for the same event. In this case, DynamoRIO sequences event callbacks in reverse order of when they were registered. In other words, the first registered callback receives event notification last. This scheme gives priority to a callback registered earlier, since it can override or modify the actions of clients registered later. Note that DynamoRIO calls each client's <a class="el" href="dr__api_8h.html#a20a4dc9da7f6bb9121e30bb3570c6961">dr_init()</a> routine according to the client's priority (see <a class="el" href="page_deploy.html#multi_client">Multiple Clients</a> and <a class="el" href="dr__config_8h.html#ae9e35bfc0682dd3bee71eb8992d9eca3">dr_register_client()</a> in the deployment API).</p>
<p>Systems registering multiple callbacks for a single event should be aware that client modifications are visible in subsequent callbacks. DynamoRIO makes no attempt to mitigate interference among callback functions. It is the responsibility of a client to ensure compatibility among its callback functions and the callback functions of other clients.</p>
<p>Clients can also unregister a callback using the appropriate unregister routine (see <a class="el" href="dr__events_8h.html" title="Event callback registration routines.">dr_events.h</a>). While unusual, it is possible for one callback routine to unregister another. In this case, DynamoRIO still calls routines that were registered before the event. Unregistration takes effect before the next event.</p>
<p>On Linux, an exec (SYS_execve) does NOT result in an exit event, but it WILL result in the client library being reloaded and its <a class="el" href="dr__api_8h.html#a20a4dc9da7f6bb9121e30bb3570c6961">dr_init()</a> routine being called again. The system call events can be used for notification of SYS_execve.</p>
<h1><a class="anchor" id="sec_utils"></a>
Common Utilities</h1>
<p>DynamoRIO provides clients with a powerful library of utilities for custom runtime code transformations. The interface includes explicit support for creating <em>transparent</em> clients. See the section on <a class="el" href="transparency.html">Client Transparency</a> for a full discussion of the importance of remaining transparent when operating in the same process as the application. DynamoRIO provides common resources clients can use to avoid reliance on shared libraries that may be in use by the application. The client should only use external resources through DynamoRIO's own API, through DynamoRIO Extensions (see <a class="el" href="using.html#sec_extensions">DynamoRIO Extensions</a>), through direct system calls, or via an external agent in a separate process that communicates with the client (see <a class="el" href="using.html#sec_comm">Communication</a>). Third-party libraries can be used if they are linked statically or loaded privately and there is no possibility of global resource conflicts (e.g., a third-party library's memory allocation must be wrapped): see <a class="el" href="using.html#sec_extlibs">Using External Libraries</a> for more details.</p>
<p>DynamoRIO's API provides:</p>
<ul>
<li>Memory allocation: both thread-private (faster as it incurs no synchronization costs) and thread-shared</li>
<li>Thread-local storage</li>
<li>Thread-local stack separate from the application stack</li>
<li>Simple mutexes</li>
<li>File creation, reading, and writing</li>
<li>Address space querying</li>
<li>Application module iterator</li>
<li>Processor feature identification</li>
<li>Extra thread creation</li>
<li>Symbol lookup (currently Windows-only)</li>
<li>Auxiliary library loading</li>
</ul>
<p>See <a class="el" href="dr__tools_8h.html" title="Main API routines, including transparency support.">dr_tools.h</a> and <a class="el" href="dr__proc_8h.html" title="Utility routines for identifying features of the processor.">dr_proc.h</a> for specifics of each routine.</p>
<p>Another class of utilities provided by DynamoRIO are structures and routines for decoding, encoding, and manipulating IA-32 and AMD64 instructions. These are described in <a class="el" href="API_BT.html#sec_IR">Instruction Representation</a>.</p>
<p><a class="anchor" id="subsec_forwards"></a>In addition, on Windows, DynamoRIO provides a number of utility functions that it fowards to a core Windows system library that we believe to be safe for clients to use:</p>
<ul>
<li>wcstoul</li>
<li>wcstombs</li>
<li>wcstol</li>
<li>wcsstr</li>
<li>wcsspn</li>
<li>wcsrchr</li>
<li>wcspbrk</li>
<li>wcsncpy</li>
<li>wcsncmp</li>
<li>wcsncat</li>
<li>wcslen</li>
<li>wcscspn</li>
<li>wcscpy</li>
<li>wcscmp</li>
<li>wcschr</li>
<li>wcscat</li>
<li>towupper</li>
<li>towlower</li>
<li>toupper</li>
<li>tolower</li>
<li>tan</li>
<li>strtoul</li>
<li>strtol</li>
<li>strstr</li>
<li>strspn</li>
<li>strrchr</li>
<li>strpbrk</li>
<li>strncpy</li>
<li>strncmp</li>
<li>strncat</li>
<li>strlen</li>
<li>strcspn</li>
<li>strcmp</li>
<li>strchr</li>
<li>sscanf</li>
<li>sqrt</li>
<li>sprintf</li>
<li>sin</li>
<li>qsort</li>
<li>pow</li>
<li>memset</li>
<li>memmove</li>
<li>memcpy</li>
<li>memcmp</li>
<li>memchr</li>
<li>mbstowcs</li>
<li>log</li>
<li>labs</li>
<li>isxdigit</li>
<li>iswxdigit</li>
<li>iswspace</li>
<li>iswlower</li>
<li>iswdigit</li>
<li>iswctype</li>
<li>iswalpha</li>
<li>isupper</li>
<li>isspace</li>
<li>ispunct</li>
<li>isprint</li>
<li>islower</li>
<li>isgraph</li>
<li>isdigit</li>
<li>iscntrl</li>
<li>isalpha</li>
<li>isalnum</li>
<li>floor</li>
<li>fabs</li>
<li>cos</li>
<li>ceil</li>
<li>atol</li>
<li>atoi</li>
<li>atan</li>
<li>abs</li>
<li>_wtol</li>
<li>_wtoi64</li>
<li>_wtoi</li>
<li>_wcsupr</li>
<li>_wcsnicmp</li>
<li>_wcslwr</li>
<li>_wcsicmp</li>
<li>_vsnprintf</li>
<li>_ultow</li>
<li>_ultoa</li>
<li>_ui64toa</li>
<li>_toupper</li>
<li>_tolower</li>
<li>_strupr</li>
<li>_strnicmp</li>
<li>_strlwr</li>
<li>_stricmp</li>
<li>_strcmpi</li>
<li>_snwprintf</li>
<li>_snprintf</li>
<li>_memicmp</li>
<li>_memccpy</li>
<li>_ltow</li>
<li>_ltoa</li>
<li>_itow</li>
<li>_itoa</li>
<li>_i64tow</li>
<li>_i64toa</li>
<li>_ftol</li>
<li>_fltused</li>
<li>_chkstk</li>
<li>_aullshr</li>
<li>_aullrem</li>
<li>_aulldiv</li>
<li>_atoi64</li>
<li>_allshr</li>
<li>_allshl</li>
<li>_allrem</li>
<li>_allmul</li>
<li>_alldiv</li>
<li>__toascii</li>
<li>__iscsymf</li>
<li>__iscsym</li>
<li>__isascii</li>
</ul>
<p>In general, these routines match their standard C library counterparts. However, be warned that some of these may be more limited. In particular, _vsnprintf and _snprintf do not support floating-point values. DynamoRIO provides its own <a class="el" href="dr__tools_8h.html#ab0c5f2529d9c076b5b0b0e92a70834b7">dr_snprintf()</a> that does support floating-point values, but does not support printing wide characters. When printing floating-point values be sure to <a class="el" href="transparency.html#sec_trans_floating_point">save the application's floating point state</a> so as to avoid corrupting it.</p>
<h1><a class="anchor" id="sec_64bit_reach"></a>
64-Bit Reachability</h1>
<p>To simplify reachability in a 64-bit address space, DynamoRIO guarantees that all of its code caches are located within a single 2GB memory region. It also places all client memory allocated through <a class="el" href="dr__tools_8h.html#a4274226adda06339e247e4a311abdd9b">dr_thread_alloc()</a>, <a class="el" href="dr__tools_8h.html#a60faa40f7e8c819c34fd25cb367c5473">dr_global_alloc()</a>, <a class="el" href="dr__tools_8h.html#ac32b5be072876c25a832d510efeba6e4">dr_nonheap_alloc()</a>, or <a class="el" href="dr__tools_8h.html#a3cfff0780cf83588e3d71da552490eb7">dr_custom_alloc()</a> with <a class="el" href="dr__tools_8h.html#abb7e20e83f7b8e1b65428e45c8ab4211ab33a2e990410bf314bdebe6a25aa06e1">DR_ALLOC_CACHE_REACHABLE</a> in the same region.</p>
<p>DynamoRIO loads client libraries and Extensions (but not copies of system libraries) within 32-bit reachability of its code caches. Typically, the code cache region is located in the low 4GB of the address space; thus, to avoid relocations at client library load time, it is recommended to set a preferred client library base in the low 4GB.</p>
<p>The net result is that any static data or code in a client library, or any data allocated using DynamoRIO's API routines (except <a class="el" href="dr__tools_8h.html#ad6201fa3676b0afb76f91f15822cf0d1">dr_raw_mem_alloc()</a> or <a class="el" href="dr__tools_8h.html#a3cfff0780cf83588e3d71da552490eb7">dr_custom_alloc()</a>), is guaranteed to be directly reachable from code cache code. However, memory allocated through system libraries (including malloc, operator new, and HeapAlloc), as well as DynamoRIO's own internally-used heap memory, is <em>not</em> guaranteed to be reachable: only memory directly allocated via DynamoRIO's API. The <a class="el" href="using.html#op_reachable_heap">-reachable_heap runtime option</a> can be used to guarantee that all memory is reachable, at the risk of running out memory due to the smaller space of available memory.</p>
<p>To make more space available for the code caches when running larger applications, or for clients that use a lot of heap memory that is not directly referenced from the cache, we recommend that <a class="el" href="dr__tools_8h.html#a3cfff0780cf83588e3d71da552490eb7">dr_custom_alloc()</a> be called to obtain memory that is not guaranteed to be reachable from the code cache (by not passing <a class="el" href="dr__tools_8h.html#abb7e20e83f7b8e1b65428e45c8ab4211ab33a2e990410bf314bdebe6a25aa06e1">DR_ALLOC_CACHE_REACHABLE</a>). This frees up space in the reachable region.</p>
<p>When inserting calls, <a class="el" href="dr__ir__utils_8h.html#af2a3575059c29dae25ab02c9eb1d0ce9">dr_insert_call()</a> and <a class="el" href="dr__ir__utils_8h.html#ae7b7bd1e750b8a24ebf401fb6a6d6d5e">dr_insert_clean_call()</a> assume that the call is destined for encoding into the code cache-reachable memory region, when determining whether a direct or indirect call is needed. An indirect call will clobber r11. Use <a class="el" href="dr__ir__utils_8h.html#a8640a5d47dcf82be4e6a5cf77bd6d967">dr_insert_clean_call_ex()</a> with <a class="el" href="dr__ir__utils_8h.html#af1b1bc23c42ffb7452568176b09b1212a9fe53fc77afb460ba31666995df5b6c9">DR_CLEANCALL_INDIRECT</a> to ensure reachability when encoding to a location other than DR's regular code region, or when a clean call is not needed, <a class="el" href="dr__ir__utils_8h.html#a5da72f3ac1f72d1abd12184d66b83f32">dr_insert_call_ex()</a> takes in a target encode location for more flexible determination of direct versus indirect.</p>
<p>DynamoRIO does not guarantee that any of its memory is allocated in the lower 4GB of the address space. However, it provides several features to make it easier to reference addresses absolutely:</p>
<ul>
<li>For directly referencing a global variable <code>var</code> in a client library, the client can create an operand with the address <code>&amp;var</code> and it will auto-magically turn into a pc-relative addressing mode. <a class="el" href="dr__ir__macros_8h.html#a54b8bd667a8a940e94bfcc7842c958eb">OPND_CREATE_ABSMEM()</a> directly creates a pc-relative operand, while <a class="el" href="dr__ir__opnd_8h.html#a6c4e5d5376ce4dc1ba7081119d97a16d">opnd_create_abs_addr()</a> will convert to a pc-relative operand when an absolute reference will not encode. An <a class="el" href="dr__ir__opnd_8h.html#a429f69f7bc430cf278b5702818b25fcc">opnd_create_rel_addr()</a> operand will also convert to an absolute reference when that will reach but a pc-relative reference will not.</li>
</ul>
<ul>
<li>When using an address as an immediate, use the routines <a class="el" href="dr__events_8h.html#a01cf5156d74cebff5bcf78a3dc0368a6">instrlist_insert_mov_immed_ptrsz()</a> or <a class="el" href="dr__events_8h.html#a5090f76aaf78dbcb3f07c7a345c38f18">instrlist_insert_push_immed_ptrsz()</a> to conveniently insert either one or two instructions depending on whether the address is in the lower 4GB or not.</li>
</ul>
<ul>
<li>When using an <code><a class="el" href="structinstr__t.html">instr_t</a></code> pointer as an immediate, use the routines <a class="el" href="dr__events_8h.html#a0576d14a61e116a9608700c492ac9c32">instrlist_insert_mov_instr_addr()</a> or <a class="el" href="dr__events_8h.html#ad2fd93ab0ee30ad46280a08bc5876133">instrlist_insert_push_instr_addr()</a> to conveniently insert either one or two instructions depending on whether the resulting <a class="el" href="structinstr__t.html">instr_t</a> encoded address is in the lower 4GB or not.</li>
</ul>
<h1><a class="anchor" id="sec_utf8"></a>
String Encoding</h1>
<p>All strings in the DynamoRIO API, whether input or output parameters, are encoded as UTF-8. DynamoRIO will internally convert to UTF-16 when interacting with the Windows kernel. A client can use <a class="el" href="dr__tools_8h.html#ab0c5f2529d9c076b5b0b0e92a70834b7">dr_snprintf()</a> or <a class="el" href="dr__tools_8h.html#a67c362b4605972c0d54142c4469e45c6">dr_snwprintf()</a> with the <code>S</code> format code to convert between UTF-8 and UTF-16 on its own. (The _snprintf() function forwarded to ntdll does not perform that conversion.)</p>
<h1><a class="anchor" id="sec_build"></a>
Building a Client</h1>
<p>To use the DynamoRIO API, a client should include the main DynamoRIO header file:</p>
<div class="fragment"><div class="line"><span class="preprocessor">#include &quot;<a class="code" href="dr__api_8h.html" title="Top-level include file for DynamoRIO API.">dr_api.h</a>&quot;</span></div>
</div><!-- fragment --><p>The client's target operating system and architecture must be specified by setting pre-processor defines before including the DynamoRIO header files. The appropriate library must then be linked with. The define choices are:</p>
<ol type="1">
<li><code>WINDOWS</code>, <code>LINUX</code>, or (coming soon) <code>MACOS</code> </li>
<li><code>X86_32</code> or <code>X86_64</code> </li>
</ol>
<p>Currently we provide a private loader for both Windows and Linux. With private loading, clients use a separate copy of each library from any copy used by the application.</p>
<p>If the private loader is deliberately disabled, for transparency reasons (see <a class="el" href="transparency.html">Client Transparency</a>), clients should be self-contained and should not share libraries with the application. Without the private loader, 64-bit clients must take care to try and load themselves within reachable range of DynamoRIO's code caches by setting a preferred base address, although this may not always be honored by the system loader.</p>
<p>The DynamoRIO release supplies <a href="http://www.cmake.org">CMake</a> configuration files to facilitate building clients with the proper compiler and linker flags. CMake is a cross-platform build system that generates Makefiles or other development system project files. A <code>DynamoRIOConfig.cmake</code> configuration file, along with supporting files, is distributed in the <code>cmake/</code> directory.</p>
<p>In its <code>CMakeLists.txt</code> file, a client should first invoke a <code>find_package(DynamoRIO)</code> command. This can optionally take a version parameter. This adds DynamoRIO as an imported target. If found, the client should then invoke the <code>configure_DynamoRIO_client()</code> function in order to configure build settings. Here is an example:</p>
<div class="fragment"><div class="line">add_library(myclient SHARED myclient.c)</div>
<div class="line">find_package(DynamoRIO)</div>
<div class="line">if (NOT DynamoRIO_FOUND)</div>
<div class="line">  message(FATAL_ERROR &quot;DynamoRIO package required to build&quot;)</div>
<div class="line">endif(NOT DynamoRIO_FOUND)</div>
<div class="line">configure_DynamoRIO_client(myclient)</div>
</div><!-- fragment --><p>Note that when building a 32-bit client in Linux using <code>gcc</code>, the stack alignment should be 4-byte only. Using the function <code>configure_DynamoRIO_client()</code> will configure the build settings correctly. Otherwise, appropriate options should be passed to the compiler: e.g., <code>-mpreferred-stack-boundary=2</code>.</p>
<p>The <code>samples/CMakeLists.txt</code> file in the release package serves as another example. The top of <code>DynamoRIOConfig.cmake</code> contains detailed instructions as well.</p>
<p>When configuring, the <code>DynamoRIO_DIR</code> CMake variable can be passed in to identify the directory that contains the <code>DynamoRIOConfig.cmake</code> file. For example:</p>
<div class="fragment"><div class="line">mkdir ../build</div>
<div class="line">cd ../build</div>
<div class="line">cmake -DDynamoRIO_DIR=$DYNAMORIO_HOME/cmake ../myclient</div>
<div class="line">make</div>
</div><!-- fragment --><p>The compiler needs to be configured prior to invoking cmake. If using gcc with a non-default target platform, the <code>CFLAGS</code> and <code>CXXFLAGS</code> environment variables should be set prior to invoking cmake. For example, to configure a 32-bit client when gcc's default is 64-bit:</p>
<div class="fragment"><div class="line">mkdir ../build</div>
<div class="line">cd ../build</div>
<div class="line">CFLAGS=-m32 cmake -DDynamoRIO_DIR=$DYNAMORIO_HOME/cmake ../myclient</div>
<div class="line">make</div>
</div><!-- fragment --><p>Note that <code>CXXFLAGS</code> should be set instead for a C++ client, and both should be set when building both types of clients from the same configuration (e.g., <code>samples/CMakeLists.txt</code>).</p>
<p>To improve clean call performance (see <a class="el" href="API_BT.html#sec_clean_call">Clean Calls</a> and <a class="el" href="using.html#op_cleancall">-opt_cleancall</a>), we recommend high levels of optimization when building a client.</p>
<p>If a client is not using CMake, the appropriate compiler and linker flags can be gleaned from <code>DynamoRIOConfig.cmake</code>. One method is to invoke CMake to generate a Makefile and then build with <code>VERBOSE=1</code>. We also summarize here the key flags required for 32-bit clients for <code>gcc:</code> </p>
<div class="fragment"><div class="line">gcc -fPIC -shared -lgcc -DLINUX -DX86_32 -I$DYNAMORIO_HOME/include my-client.c</div>
</div><!-- fragment --><p>And for <code>cl:</code> </p>
<div class="fragment"><div class="line">cl my-client.c /I$DYNAMORIO_HOME/include /GS- /DWINDOWS /DX86_32</div>
<div class="line">   /link /libpath:$DYNAMORIO_HOME/bin dynamorio.lib /dll /out:my-client.dll</div>
</div><!-- fragment --><p>For a 64-bit client with <code>cl:</code> </p>
<div class="fragment"><div class="line">cl my-client.c /I$DYNAMORIO_HOME/include /GS- /DWINDOWS /DX86_64</div>
<div class="line">   /link /libpath:$DYNAMORIO_HOME/bin dynamorio.lib /dll /out:my-client.dll</div>
<div class="line">   /base:0x72000000 /fixed</div>
</div><!-- fragment --><p>For 64-bit Linux clients, setting the preferred base takes several steps. Refer to <code>DynamoRIOConfig.cmake</code> for details.</p>
<p>To make clean call sequences more likely to be optimized, it is recommended to compile the client with optimizations, <code>-O2</code> for gcc or <code>/O2</code> for cl.</p>
<h1><a class="anchor" id="sec_extensions"></a>
DynamoRIO Extensions</h1>
<p>DynamoRIO supports extending the API presented to clients through separate libraries called DynamoRIO Extensions. Extensions are meant to include features that may be too costly to make available by default or features contributed by third parties whose licensing requires using a separate library. Extensions can be either static libraries linked with clients at build time or dynamic libraries loaded at runtime. A private loader is used to load dynamic Extensions.</p>
<p>Current Extensions provide symbol access and container data structures. Each Extension has its own documentation and has its functions and data structures documented separately from the main API. See the full list of Extensions here: <a class="el" href="page_ext.html">DynamoRIO Extensions</a>.</p>
<p>Be aware that some of the DynamoRIO Extensions have LGPL licenses instead of the BSD license of the rest of DynamoRIO. Such Extensions are built as shared libraries, have their own license.txt files, and clearly identify their license in their documentation. (We also provide static versions of such libraries, but take care in using them that their LGPL licenses match your requirements.)</p>
<h1><a class="anchor" id="sec_extlibs"></a>
Using External Libraries</h1>
<p>Clients are free to use external libraries as long as those libraries do not use any global user-mode resources that would interfere with the running application, and as long as no alertable system calls are invoked on Windows (see <a class="el" href="using.html#sec_alertable">Avoid Alertable System Calls</a>). While most non-graphical non-alertable Windows API routines are supported, native threading libraries such as <code>libpthread.so</code> on Linux are known to cause problems.</p>
<p>Currently we provide a private loader for both Windows and Linux. Clients must either link statically to all libraries or load them using our private loader, which will happen automatically for shared libraries loaded in a typical manner. With private loading, the client uses a separate copy of each library from any copy used by the application. This helps to prevent re-entrancy problems (see <a class="el" href="transparency.html#sec_trans_resource">Resource Usage Conflicts</a>). Even with this separation, if these libraries use global resources there can still be conflicts. Our private loader redirects heap allocation in the main process heap to instead use DynamoRIO's internal heap. The loader also attempts to isolate other global resource usage and global callbacks. Please file reports on any transparency problems observed when using the private loader.</p>
<p>By default, all Windows clients link with libc. To instead use the libc subset of routines forwarded from the DynamoRIO library to <code>ntdll.dll</code> (which keeps clients more lightweight and is usually sufficient for most C code), set this variable prior to invoking configure_DynamoRIO_client():</p>
<div class="fragment"><div class="line">  <span class="keyword">set</span>(DynamoRIO_USE_LIBC OFF)</div>
</div><!-- fragment --><p>C++ clients and standalone clients link with libc by default.</p>
<h2><a class="anchor" id="sec_alertable"></a>
Avoid Alertable System Calls</h2>
<p>On Windows, DynamoRIO does not support a client (or a library used by a client) making alertable system calls. These are system calls that can be interrupted for delivery of callbacks or asynchronous procedure calls. At the Windows API layer, they include many graphical routines, any Wait function invoked with <code>alertable=TRUE</code> (e.g., WaitForSingleObjectEx or WaitForMultipleObjectsEx), any Windows message queue function (GetMessage, SendMessage, ReplyMessage), and asynchronous i/o. In general, avoiding graphical, windowing, or asynchronous i/o library or system calls is advisable. DynamoRIO does not guarantee correct execution when a callback arrives during client code execution.</p>
<h2><a class="anchor" id="sec_rpath"></a>
DynamoRIO Library Search Paths</h2>
<p>DynamoRIO's loader searches for libraries in approximately the same manner as the system loader. It also has support for automatically locating Extension libraries that are packaged in the usual place in the DynamoRIO file hierarchy.</p>
<p>DynamoRIO supports setting DT_RPATH for ELF clients, via setting the DynamoRIO_RPATH variable to ON prior to invoking configure_DynamoRIO_client(). On Windows, setting that variable will create a "&lt;client_basename&gt;.drpath" text file that contains a list of paths. At runtime, DynamoRIO's loader will parse this file and add each newline-separated path to its list of search paths. This file is honored on Linux as well, though it is not automatically created there. This allows clients a cross-platform mechanism to use third-party libraries in locations of their choosing.</p>
<h2><a class="anchor" id="subsec_avoid_redir"></a>
Deliberately Invoking Application Routines</h2>
<p>Sometimes, a client wishes to invoke system library routines with the application context, rather than having them redirected and isolated by DynamoRIO. This can be accomplished using dynamic binding rather than static: dynamically looking up each desired library routine via DR's own routines (such as <a class="el" href="dr__tools_8h.html#a8da7923ecc4e020e31442bcc8d9f8d3e">dr_get_proc_address()</a>). (Using <code>GetProcAddress</code> will not work for this purpose as the result will be redirected.)</p>
<h2><a class="anchor" id="subsec_no_loader"></a>
When Private Loader is Disabled</h2>
<p>On Linux, if the private loader is deliberately disabled, ld provides the -wrap option, which allows us to override the C library's memory heap allocation routines with our own. For convenience, DynamoRIO exports <a class="el" href="dr__tools_8h.html#a3687f50774c89e7a09833a71adbb7771">__wrap_malloc()</a>, <a class="el" href="dr__tools_8h.html#adcaad79adf4fc109015dd6a2d49b9031">__wrap_realloc()</a>, and <a class="el" href="dr__tools_8h.html#a82dca5b3d5bfbd3de8891502badd861e">__wrap_free()</a> for this purpose. These routines behave like their C library counterparts, but operate on DynamoRIO's global memory pool. Use the -Xlinker flag with gcc to replace the libc routines with DynamoRIO's _wrap routines, e.g.,</p>
<div class="fragment"><div class="line">  gcc -Xlinker -wrap=malloc -Xlinker -wrap=realloc -Xlinker -wrap=free ...</div>
</div><!-- fragment --><p>The ability to override the memory allocation routines makes it convenient to develop C++ clients that use the <em>new</em> and <em>delete</em> operators (as long as those operators are implemented using malloc and free). In particular, heap allocation is required to use the C++ Standard Template Library containers. When developing a C++ client, we recommend linking statically to the C++ runtime library if not using the provided private loader.</p>
<p>On Linux, this is most easily accomplished by specifying the path to the static version of the library on the gcc command line. gcc's -print-file-name option is useful for discovering this path, e.g.,</p>
<div class="fragment"><div class="line">  g++ -print-file-name=libstdc++.a</div>
</div><!-- fragment --><p>A full gcc command line for building a C++ client when disabling the private loader (which is not the default) might look something like this (note that this requires static versions of the standard libraries that were built PIC, which is not the case in modern binary distributions and often requires building from source):</p>
<div class="fragment"><div class="line">g++ -o my-client.so -I&lt;header dir&gt; \</div>
<div class="line">  -fPIC -shared -nodefaultlibs \</div>
<div class="line">  -Xlinker -wrap=malloc -Xlinker -wrap=realloc -Xlinker -wrap=free \</div>
<div class="line">  `g++ -print-file-name=libstdc++.a` \</div>
<div class="line">  `g++ -print-file-name=libgcc.a` \</div>
<div class="line">  `g++ -print-file-name=libgcc_eh.a` \</div>
<div class="line">  my-client.cpp</div>
</div><!-- fragment --><h2><a class="anchor" id="subsec_cpp"></a>
C++ Clients</h2>
<p>The 3.0 version of DynamoRIO added experimental full support for C++ clients using the STL and other libraries.</p>
<p>On Windows, when using the Microsoft Visual C++ compiler, we recommend using the <code>/MT</code> compiler flag to request a static C library. The client will still use the <code>kernel32.dll</code> library but our private loader will load a separate copy of that library and redirect heap allocation automatically. Our private loader does not yet support locating SxS (side-by-side) libraries, so using <code>/MD</code> will most likely not work unless using a version of the Visual Studio compiler other than 2005 or 2008.</p>
<p>We do not recommend that a client or its libraries invoke their own system calls as this bypasses DynamoRIO's monitoring of changes to the process address space and changes to threads or control flow. Such system calls will also not work properly on Linux when using sysenter on some systems. If you see an assert to that effect in debug build on Linux, try the <a class="el" href="using.html#op_sysenter">-sysenter_is_int80</a> option.</p>
<h1><a class="anchor" id="sec_comm"></a>
Communication</h1>
<p>Due to transparency limitations (see <a class="el" href="transparency.html">Client Transparency</a>), DynamoRIO can only support certain communication channels in and out of the target application process. These include:</p>
<ul>
<li>DynamoRIO deployment control and runtime options: see <a class="el" href="page_deploy.html">Deployment</a> and <a class="el" href="using.html#sec_options">Fine-Tuning DynamoRIO: Runtime Parameters</a>. In particular, the deployment API allows users to pass up-front runtime information to the client.</li>
<li>Nudges: Since polling requires extra threads, and DynamoRIO tries not to create permanent extra threads (see <a class="el" href="transparency.html#sec_trans_thread">Thread Transparency</a>), a mechanism called <em>nudges</em> are the preferred mechanism for pushing data into the process. Nudges are used to notify DynamoRIO that it needs to re-read its options, or perform some other action. DynamoRIO also provides a custom nudge event that can be used by clients. See <a class="el" href="dr__config_8h.html#a9df3d364222898cebc24264a161e2a5f">dr_nudge_process()</a> and <a class="el" href="dr__events_8h.html#a9037603d0bd5bfca4198011adb8d10eb">dr_register_nudge_event()</a>.</li>
<li>Files can be used to send data out. An external process can wait on the file.</li>
</ul>
<h1><a class="anchor" id="sec_options"></a>
Fine-Tuning DynamoRIO: Runtime Parameters</h1>
<p>DynamoRIO's behavior can be fine-tuned using runtime parameters. Options are specified via <code>drconfig</code>, <code>drrun</code>, or <a class="el" href="dr__config_8h.html#a10d7c5dbc9a055fa6c18bf3f2a6eea46">dr_register_process()</a>. See <a class="el" href="page_deploy.html">Deployment</a>.</p>
<ul>
<li><p class="startli"><b>-no_follow_children</b>: <a class="anchor" id="op_children"></a> By default, DynamoRIO follows all child processes. When this option is disabled via <code>-no_follow_children</code>, DynamoRIO follows only into child processes for which a configuration file exists (typically created by <code>drconfig</code>; see <a class="el" href="page_deploy.html">Deployment</a>). On Linux, forked children are always followed and this option only affects execve.</p>
<p class="startli">To follow all children in general but exclude certain children, leave <code>-follow_children</code> on (the default) and create config files that exclude the desired applications by running <code>drconfig</code> with the <code>-norun</code> option.</p>
</li>
</ul>
<ul>
<li><b>-opt_memory</b>: <a class="anchor" id="op_memory"></a> Reduce memory usage, but potentially at the cost of performance. This option can result in memory savings as high as 20%, and usually incurs no noticable performance degradation. However, it conflicts with the <a class="el" href="using.html#op_enable">-enable_full_api option</a> and cannot be used with <a class="el" href="dr__tools_8h.html#a56909cf76e4a71fca13731053ef48928">dr_unlink_flush_region()</a>.</li>
</ul>
<ul>
<li><b>-opt_cleancall</b> <em>&lt;number&gt;</em>: <a class="anchor" id="op_cleancall"></a> Optimize (shrink or inline) the clean call sequences (see <a class="el" href="API_BT.html#sec_clean_call">Clean Calls</a>). When DynamoRIO analyzes the callee and optimizes each clean call invocation, it assumes that a client will not modify the clean call callee or application instructions after the inserted clean call. If a client changes application instructions after an inserted clean call, the client may need to reduce the -opt_cleancall level to preserve correct execution. The clean call will only be optimized if it is a leaf function. Currently, the callee will be inlined only if it is small, has at most one argument, and has no control flow other than for the PIC base. Compiling the client with optimizations makes clean call sequences more likely to be optimized. The optimization results (e.g. whether the inserted clean call is inlined or not, and which registers were saved on each context switch) are logged. Users can run DynamoRIO debug build with the runtime option "-loglevel 2 -logmask 0x02000000" (the logmask is optional but reduces the logfile size significantly) and grep for "CLEANCALL" in the log file to retrieve the information about clean call optimization. There are four optimization levels. By default, the clean call optimization level is 2.<ul>
<li>0: no optimization.</li>
<li>1: callee register usage analysis and optimization on context switch.</li>
<li>2: simple callee inline optimization, callee-save register analysis, and aflags usage analysis on the instruction list to be inserted.</li>
<li>3: more aggressive, but potentially unsafe, optimizations.</li>
</ul>
</li>
</ul>
<ul>
<li><b>-opt_speed</b>: <a class="anchor" id="op_speed"></a> By default, DynamoRIO provides a more straightforward code stream to clients in lieu of performance optimizations. This option attempts to obtain higher performance with potential loss of client simplicity. In particular, unconditional branches (both jumps and calls) and in some cases indirect calls may be elided in basic blocks. See also <a class="el" href="release_notes.html#sec_limit_perf">Performance Limitations</a>. Note that <a class="el" href="dr__ir__utils_8h.html#a919e2106df67eaaa5bc6c49d736543b5">dr_insert_mbr_instrumentation()</a> is not supported when -opt_speed is specified.</li>
</ul>
<ul>
<li><b>-stack_size</b> <em>&lt;number&gt;</em>: <a class="anchor" id="op_stack_size"></a> DynamoRIO's per-thread stack is limited to 56KB by default (this may seem small, but this is much larger than its size when no client is present). This parameter can be used to increase the size; however, larger stack sizes use significantly more memory when targeting applications with hundreds of threads. The parameter can take a 'K' suffix, and must be a multiple of the page size (4K). This stack is used by the routines <a class="el" href="dr__ir__utils_8h.html#ae7b7bd1e750b8a24ebf401fb6a6d6d5e">dr_insert_clean_call()</a>, <a class="el" href="dr__ir__utils_8h.html#a9647e1300201596bc818ca33c95d4cc6">dr_swap_to_clean_stack()</a>, <a class="el" href="dr__ir__utils_8h.html#a4608ec2db2a288aa5e2a53bb6d19054d">dr_prepare_for_call()</a>, <a class="el" href="dr__ir__utils_8h.html#a359744bc2776333fbf8f057931ca8eeb">dr_insert_call_instrumentation()</a>, <a class="el" href="dr__ir__utils_8h.html#a919e2106df67eaaa5bc6c49d736543b5">dr_insert_mbr_instrumentation()</a>, <a class="el" href="dr__ir__utils_8h.html#abe09a1a1ca19b343279a65141c20f0a1">dr_insert_cbr_instrumentation()</a>, and <a class="el" href="dr__ir__utils_8h.html#a3647b439211a8cd70c40478a4113e128">dr_insert_ubr_instrumentation()</a>. The stack is started fresh for each use, so <em>no persistent state may be stored on it</em>.</li>
<li><b>-thread_private</b>: <a class="anchor" id="op_thread_priv"></a> By default, DynamoRIO's code caches are shared across threads. This option requests code caches that are private to each thread. For applications with many threads, thread-private code caches use more memory. However, they can be more efficient, particularly when inserting thread-specific instrumentation.</li>
</ul>
<ul>
<li><b>-disable_traces</b>: By default, DynamoRIO builds both a <em>basic block</em> code cache and a <em>trace</em> code cache (see <a class="el" href="API_BT.html#sec_IR">Instruction Representation</a>). This option disables trace building, which can have a negative performance impact. When running large, short-running applications, however, disabling traces can improve performance. When traces are disabled, <a class="el" href="dr__events_8h.html#a88a19a6822654caf18c017e145f48a57">dr_register_trace_event()</a> has no effect. DynamoRIO tries to keep traces transparent to a client who is interested in all code and not only hot code, so there is rarely a reason to disable traces.</li>
</ul>
<ul>
<li><b>-enable_full_api</b>: <a class="anchor" id="op_enable"></a> DynamoRIO's default internal options balance performance with API usability. A few API functions, such as <a class="el" href="dr__tools_8h.html#a56909cf76e4a71fca13731053ef48928">dr_unlink_flush_region()</a>, are incompatible with this default mode. Client users can gain access to the entire set of API functions with -enable_full_api. Note that this option may result in a small performance degradation.</li>
</ul>
<ul>
<li><b>-reachable_heap</b>: <a class="anchor" id="op_reachable_heap"></a> By default, DynamoRIO guarantees that heap allocated directly through its API routines <a class="el" href="dr__tools_8h.html#a4274226adda06339e247e4a311abdd9b">dr_thread_alloc()</a>, <a class="el" href="dr__tools_8h.html#a60faa40f7e8c819c34fd25cb367c5473">dr_global_alloc()</a>, <a class="el" href="dr__tools_8h.html#ac32b5be072876c25a832d510efeba6e4">dr_nonheap_alloc()</a>, or <a class="el" href="dr__tools_8h.html#a3cfff0780cf83588e3d71da552490eb7">dr_custom_alloc()</a> with <a class="el" href="dr__tools_8h.html#abb7e20e83f7b8e1b65428e45c8ab4211ab33a2e990410bf314bdebe6a25aa06e1">DR_ALLOC_CACHE_REACHABLE</a> is reachable by a 32-bit displacement from the code cache. However, it does not guarantee that memory allocated through system libraries (including malloc, operator new, and HeapAlloc) or DynamoRIO's own internal memory is reachable. Turning this option on combines all of the heap memory such that it is all guaranteed to be reachable from the code cache, at the risk of running out memory due to the smaller space of available memory.</li>
</ul>
<ul>
<li><b>-max_bb_instrs</b>: DynamoRIO stops building a basic block if it hits this application instruction count limit before hitting control flow or other block termination conditions. The default value is 1024; lower it if extensive client instrumentation is running into code cache size limit asserts.</li>
</ul>
<ul>
<li><b>-max_trace_bbs</b>: DynamoRIO will not build a trace with larger than this number of constituent basic block. The default value is 128; lower it if extensive client instrumentation is running into code cache size limit asserts.</li>
</ul>
<ul>
<li><b>-sysenter_is_int80</b>: <a class="anchor" id="op_sysenter"></a> This option only applies to Linux. If sysenter is the system call gateway, DynamoRIO normally hooks the vsyscall vdso page when it can. This option requests that DynamoRIO convert sysenter into int 0x80 instead. See <a class="el" href="using.html#sec_extlibs">Using External Libraries</a>.</li>
</ul>
<ul>
<li><b>-multi_thread_exit</b>: By default, DynamoRIO synchronizes with all remaining threads at process exit time and the process exit event executes with only one live thread. This option requests that in release build the synchronization be avoided. The process exit event must be written in a thread-safe manner. Note that if thread exit events are registered, to avoid the synchronization the -skip_thread_exit_at_exit option must also be set. These options can also be enabled programmatically via <a class="el" href="dr__events_8h.html#acede43748af42c6334a19fc30e48c5f4">dr_set_process_exit_behavior()</a>.</li>
</ul>
<ul>
<li><b>-skip_thread_exit_at_exit</b>: By default, DynamoRIO synchronizes with all remaining threads at process exit time in order to safely call each thread exit event. This option requests that in release build the synchronization be avoided by removing the invocation of thread exit events at process exit time. Note that if the process exit event is registered, to avoid the synchronization the -multi_thread_exit option must also be set. These options can also be enabled programmatically via <a class="el" href="dr__events_8h.html#acede43748af42c6334a19fc30e48c5f4">dr_set_process_exit_behavior()</a>.</li>
</ul>
<ul>
<li><b>-persist</b>:<a class="anchor" id="op_persist"></a> Enables persisting of code caches to disk and re-use on subsequent runs. Caches are persisted in units that correspond to application libraries, or sometimes smaller units. Each unit is persisted to its own file in a subdirectory of the base directory specified by <code>-persist_dir</code>. See <a class="el" href="API_BT.html#sec_pcache">Persisting Code</a> for more details.</li>
</ul>
<ul>
<li><b>-persist_dir</b> <em>&lt;path&gt;</em>: Sets the base directory for persistent code cache files. If unset, the default base directory is the log directory. A different sub-directory will be created for each user inside the specified directory.</li>
</ul>
<ul>
<li><b>-translate_fpu_pc</b>:<a class="anchor" id="op_translate_fpu_pc"></a> Enables translation of the last floating-point instruction address when the last floating-point instruction is not in the same basic block as the instruction saving the FPU state. This is off by default as it incurs significant performance penalties and few applications require this feature.</li>
</ul>
<ul>
<li><b>-syntax_intel</b>: <a class="anchor" id="op_syntax_intel"></a> This option causes DynamoRIO to output all disassembly using Intel syntax rather than the default show-implicit-operands syntax. This can also be set using <a class="el" href="dr__ir__utils_8h.html#a3082c5db55039c72ae30e3276f622aae">disassemble_set_syntax()</a>.</li>
</ul>
<ul>
<li><b>-syntax_att</b>: <a class="anchor" id="op_syntax_att"></a> This option causes DynamoRIO to output all disassembly using AT&amp;T syntax rather than the default show-implicit-operands syntax. This can also be set using <a class="el" href="dr__ir__utils_8h.html#a3082c5db55039c72ae30e3276f622aae">disassemble_set_syntax()</a>.</li>
</ul>
<ul>
<li><b>-disasm_mask</b>: This option sets the disassembly style to the specified bitmask of dr_disasm_flags_t values. This option overlaps with -syntax_intel and -syntax_att. The style can also be set using <a class="el" href="dr__ir__utils_8h.html#a3082c5db55039c72ae30e3276f622aae">disassemble_set_syntax()</a>.</li>
</ul>
<ul>
<li><b>-tracedump_text</b> and <b>-tracedump_binary</b>: These options cause DynamoRIO to output all traces that were created to the log file <em>traces-shared.0.TID.html</em>, where <em>TID</em> is the thread id of the initial thread; any thread-private traces (see <a class="el" href="using.html#op_thread_priv">-thread_private option</a>) produce per-thread files <em>traces.TID.html</em>. Traces are logged whenever they are flushed from the cache (which can be during execution or at the latest at program termination). The two options select either a text dump or a binary dump. The text dump takes up considerable room and time to dump, while the binary dump requires more effort to examine. The binary trace dump format is documented in <a class="el" href="dr__tools_8h.html" title="Main API routines, including transparency support.">dr_tools.h</a>, and a sample reader is provided with this distribution.</li>
</ul>
<ul>
<li><b>-tracedump_origins</b> When selected by itself with neither -tracedump_text nor -tracedump_binary, dumps only a text list of the constituent basic block tags of each trace to the trace log file. When combined with either of -tracedump_text or -tracedump_binary, adds a full disassembly of the constituent basic blocks to the selected dump.</li>
</ul>
<p>Options controlling notifications from DynamoRIO:</p>
<ul>
<li><b>-msgbox_mask</b> <em>0xN</em>: <a class="anchor" id="op_msgbox_mask"></a> Controls whether DynamoRIO uses pop-up message boxes on Windows, or waits for a key press on Linux, when presenting information. The mask takes the following bitfields:<ul>
<li>INFORMATION = 0x1</li>
<li>WARNING = 0x2</li>
<li>ERROR = 0x4</li>
<li>CRITICAL = 0x8</li>
</ul>
<a class="el" href="dr__tools_8h.html#ad444a204e7ca45f9965cfe973470375a">dr_messagebox()</a> is not affected by -msgbox_mask. For the provided Windows debug build -msgbox_mask defaults to 0xC. On Linux the default is 0, as this feature reads from standard input and might conflict with some applications.</li>
</ul>
<dl class="section attention"><dt>Attention:</dt><dd>On Vista or higher most Windows services are currently unable to display message boxes (see <a class="el" href="release_notes.html#limits_vista_service_messagebox">Limitations</a>). Since these services also don't have an associated console for stderr printing, the <a class="el" href="using.html#op_loglevel">-loglevel</a> and <a class="el" href="using.html#op_logmask">-logmask</a> options should be used instead. For the messages that would be displayed by -msgbox_mask, setting any bit in -logmask is sufficient for the message to be included in the logfile.</dd></dl>
<ul>
<li><b>-stderr_mask</b> <em>0xN</em>: Parallel to -msgbox_mask, but controls DynamoRIO's output to standard error. This option takes the same bitfields as -msgbox_mask. The API routine <a class="el" href="dr__tools_8h.html#af91a810b83f1173a5720a955c3d0fd4a">dr_is_notify_on()</a> can be used to determine if -stderr_mask is non-zero. Messages printed to stderr will only be visible for applications that have an attached console. They will not be visible in the <code>cmd</code> console on Windows 7 or earlier or on any Windows version when running a graphical application in <code>cmd</code> (even with <a class="el" href="dr__tools_8h.html#a712de67b3f6adb6778ce302925009753">dr_enable_console_printing()</a>, as that only affects clients calling <a class="el" href="dr__tools_8h.html#abad2eddb3786e3e909ff36da39b7e31e">dr_printf()</a> or <a class="el" href="dr__tools_8h.html#a1affb1a9f1c49c1959f1a01967a0a0d9">dr_fprintf()</a>) but the output can be viewed from <code>cmd</code> by redirecting to a file. For the provided Linux debug builds, -stderr_mask defaults to 0xF; for the Linux release builds, its default is 0xE. The default on Windows is 0.</li>
</ul>
<p>Options aiding in debugging:</p>
<ul>
<li><b>-pause_on_error</b>: <a class="anchor" id="op_pause"></a> For Linux builds only, this option requests that when DynamoRIO encounters an assert or crash that it suspend the process so that a debugger can be attached.</li>
</ul>
<ul>
<li><b>-no_hide</b>: <a class="anchor" id="op_no_hide"></a> By default, DynamoRIO hides itself from the Windows module list, for transparency. However, this makes it more difficult to debug a process under DynamoRIO's control. The option -no_hide turns off this module hiding. However, the client library and any libraries it imports from will still be hidden. We provide a windbg script that can locate DynamoRIO, the client library, and all of its dependences, so this option should no longer be necessary (see <a class="el" href="using.html#sec_debugging">Diagnosing and Reporting Problems</a>). This option is for Windows only.</li>
</ul>
<p>Options available only in the debug build of DynamoRIO:</p>
<p><a class="anchor" id="op_loglevel"></a></p>
<ul>
<li><b>-loglevel</b> <em>N:</em> If N is greater than 0, DynamoRIO prints out a log of its actions. The greater the value of N, the more information DynamoRIO prints. Useful ranges are from 1 to 6. Verbosity is set to 0 by default, i.e., no log written. All log files are kept in a log directory. There is one directory per address space per run. The directories are named <em>app.NNN</em>, where <em>app</em> is the application name and <em>NNN</em> is a number that is incremented with each directory created. On Windows the directories are located by default in a subdirectory <em>logs</em> of the DynamoRIO home directory as specified in the <a class="el" href="dr__config_8h.html#a10d7c5dbc9a055fa6c18bf3f2a6eea46">dr_register_process()</a>, <code>drconfig</code>, or <code>drrun</code> configuration for the target application. The runtime option <a class="el" href="using.html#op_logdir">-logdir</a> can be used to override the default directory. There is one main log file per directory named <em>app.0.TID.html</em>, where <em>TID</em> is the thread identifier of the initial thread. There is also a log file per thread, named <em>log.N.TID.html</em>, where <em>N</em> is the thread's creation ordinal and <em>TID</em> is its thread identifier. The loglevel may be changed during program execution, but if it began at 0 then it cannot be raised later. The -logmask parameter can be used to control which DynamoRIO modules output data to the log files. <a class="el" href="dr__tools_8h.html#a332a14861f12823994465e8c9b6a3015">dr_log()</a> allows the client to write to the above logfiles.</li>
</ul>
<p><a class="anchor" id="op_logmask"></a></p>
<ul>
<li><b>-logmask</b> <em>0xN</em>: Selects which DynamoRIO modules print out logging information, at the -loglevel level. The mask is a combination of the LOG_ bitfields listed in <a class="el" href="dr__tools_8h.html" title="Main API routines, including transparency support.">dr_tools.h</a> (<a class="el" href="dr__tools_8h.html#a7574ce4aa047de1f4a564c9b441e69dc">LOG_ALL</a> selects all modules).</li>
</ul>
<p><a class="anchor" id="op_logdir"></a></p>
<ul>
<li><b>-logdir</b> <em>&lt;path&gt;</em>: Specifies the directory to use for log files. See the documentation for <a class="el" href="using.html#op_loglevel">-loglevel</a> for a description of the default log directory.</li>
</ul>
<ul>
<li><b>-ignore_assert_list</b> <b>'*'</b>: <a class="anchor" id="op_ignore_assert"></a> Ignores all DynamoRIO asserts of the form "&lt;file&gt;:1234". * may be replaced by a ; separated list of individual asserts to ignore "foo.c:333;bar.c:12".</li>
</ul>
<h1><a class="anchor" id="sec_debugging"></a>
Diagnosing and Reporting Problems</h1>
<p>When using a complex system like DynamoRIO, problems can be challenging to diagnose. This section contains some debugging tips and shows how to get help.</p>
<h2><a class="anchor" id="sec_reporting"></a>
Obtaining Help and Reporting Problems</h2>
<p>For questions and discussion, join the <a href="http://groups.google.com/group/dynamorio-users/">DynamoRIO Users group</a>.</p>
<p>For bug reports, use the <a href="http://code.google.com/p/dynamorio/issues/list">Issue Tracker</a>. Please include <a href="http://code.google.com/p/dynamorio/wiki/BugReporting">a detailed description</a> of the problem (is it an application crash? a DynamoRIO crash? a hang? a debug build assert?) and how to reproduce it.</p>
<h2><a class="anchor" id="sec_diagnosing"></a>
Troubleshooting</h2>
<ul>
<li>DynamoRIO disables itself when Windows is booted in safe mode (without networking). Thus, if a crash occurs in a Windows service under DynamoRIO, rebooting in safe mode will allow recovery.</li>
</ul>
<ul>
<li><p class="startli">If the client library doesn't seem to function for a given process, it is likely that the client library wasn't loaded due to errors.</p>
<dl class="section user"><dt></dt><dd>One of the common situations where this happens is when the target application runs as a different user than the user who created the client library. This results in the application process not having the right permissions to access the client library.</dd></dl>
<dl class="section user"><dt></dt><dd>Try running the process under the debug mode of DynamoRIO (see <a class="el" href="dr__config_8h.html#a10d7c5dbc9a055fa6c18bf3f2a6eea46">dr_register_process()</a>), where diagnostic messages are raised on errors like client library permissions. To see all messages, set the notification options like -msgbox_mask and -stderr_mask options to 0xf (see <a class="el" href="using.html#sec_options">Fine-Tuning DynamoRIO: Runtime Parameters</a>). This will alert you to the problem.</dd></dl>
</li>
<li>DynamoRIO asserts of the form "&lt;file&gt;:1234" can be suppressed with the <a class="el" href="using.html#op_ignore_assert">-ignore_assert_list '*'</a> option. * may be replaced by a ; separated lists of individual asserts to suppress as so "-ignore_assert_list 'foo.c:333;bar.c:12'".</li>
</ul>
<ul>
<li>The DynamoRIO header files have typedefs that may conflict with other header files wrapped in ifndef DR_DO_NOT_DEFINE_&lt;type&gt; to make it easier to work around such conflicts.</li>
</ul>
<h2><a class="anchor" id="sec_using_debugger"></a>
Using Debuggers</h2>
<p>A process under control of DynamoRIO can be executed within a debugger. For debugging on Windows we recommend using windbg version 6.3.0017 (<b>not</b> the newer versions, as they have problems displaying callstacks involving DynamoRIO code).</p>
<p>Normally, the debugger will not be aware of the DynamoRIO library or the client library. We provide a windbg script that locates the DynamoRIO library, the client library, and any privately-loaded dependent libraries. The script is in <code>bin32/load_syms.txt</code> and <code>bin64/load_syms64.txt</code>. To load it from windbg, execute the following command:</p>
<div class="fragment"><div class="line">  $&gt;&lt;c:\path\to\DR\bin32\load_syms.txt</div>
</div><!-- fragment --><p> When debugging often, modify the shortcut that launches windbg to include this command as a -c argument. E.g.:</p>
<div class="fragment"><div class="line"><span class="stringliteral">&quot;C:\Program Files (x86)\Debugging Tools for Windows\windbg.exe&quot;</span> -pt 1 -c <span class="stringliteral">&quot;$&gt;&lt;c:\tools\DynamoRIO\bin32\load_syms.txt&quot;</span></div>
</div><!-- fragment --><p>On Windows, the <a class="el" href="using.html#op_no_hide">-no_hide</a> option can alternatively be used so the debugger can see the DynamoRIO library, but the debugger will still not be able to see the client library or any of its dependent libraries. We recommend using our script.</p>
<p>To attach to a process on Windows, use the <a class="el" href="using.html#op_msgbox_mask">-msgbox_mask</a> option and attach the debugger while the dialog box has paused the application. On Linux, the same option can be used and the debugger attached while the application waits for enter to be pressed. Since this may not work for applications that themselves read from standard input, an alternative exists: the <a class="el" href="using.html#op_pause">-pause_on_error</a> option allows attaching a debugger when a problem occurs.</p>
<p>To run an application on Linux under a debugger from process start you can launch drrun under gdb as you would normally:</p>
<div class="fragment"><div class="line">gdb --args path/to/drrun &lt;options&gt; -- path/to/app</div>
</div><!-- fragment --><p>Because the executable changes from drrun to the app, the app cannot be re-run from gdb's prompt. To re-run an application from gdb's prompt, you can perform the work of the <code>drrun</code> tool by setting the LD_LIBRARY_PATH and LD_PRELOAD environment variables from within the debugger.</p>
<p>On Linux, the main drawback of debugging from application start rather than attaching is that breakpoint instructions (<code>int3</code>) inserted by the debugger get copied into the code cache. This includes internal debugger breakpoints automatically placed in the loader, as well as user-defined breakpoints. For example, gdb puts a breakpoint on __nptl_create_event, which is called by pthread_create and related calls. See <a href="http://code.google.com/p/dynamorio/issues/detail?id=490">http://code.google.com/p/dynamorio/issues/detail?id=490</a>. The debugger will handle these traps, but the user must tell it to continue, which is an annoyance. For user breakpoints, consider using read watchpoints on the code in question instead.</p>
<p>On Windows, if an application invokes OutputDebugString() while under a debugger, DynamoRIO can end up losing control of the application.</p>
<p>For additional tips, check the DynamoRIO wiki page on debugging: <a href="https://code.google.com/p/dynamorio/wiki/Debugging">https://code.google.com/p/dynamorio/wiki/Debugging</a> </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer" style="float:none;text-align:center"><img border=0 src="favicon.png"> &nbsp;  DynamoRIO API version 5.0.0 --- Wed Sep 10 2014 21:36:44 &nbsp; <img border=0 src="favicon.png">
</small></address>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>
